package com.tbynet.jwp.repository.spi;

import java.math.BigInteger;
import java.util.Date;
import java.util.List;
import java.util.Map;

import com.tbynet.jwp.framework.core._JwpService;
import com.tbynet.jwp.model.Usermeta;
import com.tbynet.jwp.model.Users;

/**
 * 用户服务接口 - 基于WordPress 4.9功能设计
 * @ClassName: UserService
 * @Description: 负责用户数据的获取、添加、修改、删除功能，完整实现WordPress用户系统功能
 * @Author: 佰亿互联
 * @Date: 2025年11月4日
 *
 * @Copyright: 2025 www.tbynet.com Inc. All rights reserved.
 */
public interface UserService extends _JwpService<Users> {

    // ========== WordPress 核心用户CRUD操作 ==========

    /**
     * 创建新用户 - 对应 wp_insert_user()
     *
     * @param user 用户对象
     * @return 创建的用户ID
     */
    Object createUser(Users user);

    /**
     * 删除用户 - 对应 wp_delete_user()
     *
     * @param userId 用户ID
     * @param reassignTo 重新分配内容的用户ID
     * @return 删除是否成功
     */
    boolean deleteUser(Object userId, Object reassignTo);

    // ========== WordPress 用户查询方法 ==========

    /**
     * 根据用户名或邮箱查找用户 - 对应 get_user_by()
     *
     * @param loginOrEmail 用户名或邮箱
     * @return 用户对象
     */
    Users findUserByLoginOrEmail(String loginOrEmail);

    /**
     * 根据用户名查找用户 - 对应 get_user_by('login')
     *
     * @param userLogin 用户名
     * @return 用户对象
     */
    Users findUserByLogin(String userLogin);

    /**
     * 根据邮箱查找用户 - 对应 get_user_by('email')
     *
     * @param email 邮箱
     * @return 用户对象
     */
    Users findUserByEmail(String email);

    /**
     * 根据昵称查找用户 - 对应 通过usermeta查询nickname
     *
     * @param nickname 用户昵称
     * @return 用户对象
     */
    Users findUserByNickname(String nickname);

    /**
     * 根据显示名称查找用户 - 对应 通过display_name查询
     *
     * @param displayName 显示名称
     * @return 用户列表
     */
    List<Users> findUsersByDisplayName(String displayName);

    /**
     * 根据激活密钥查找用户 - 对应 密码重置功能
     *
     * @param activationKey 激活密钥
     * @return 用户对象
     */
    Users findUserByActivationKey(String activationKey);

    /**
     * 根据用户状态查找用户
     *
     * @param userStatus 用户状态
     * @return 用户列表
     */
    List<Users> findUsersByStatus(Integer userStatus);

    // ========== WordPress 存在性检查 ==========

    /**
     * 检查用户名是否存在 - 对应 username_exists()
     *
     * @param userLogin 用户名
     * @return 是否存在
     */
    boolean isUserLoginExists(String userLogin);

    /**
     * 检查邮箱是否存在 - 对应 email_exists()
     *
     * @param email 邮箱
     * @return 是否存在
     */
    boolean isEmailExists(String email);

    /**
     * 检查用户ID是否存在
     *
     * @param userId 用户ID
     * @return 是否存在
     */
    boolean isUserIdExists(Object userId);

    // ========== WordPress 用户统计 ==========

    /**
     * 根据状态获取用户数量
     *
     * @param status 用户状态
     * @return 用户数量
     */
    long getUserCountByStatus(Integer status);

    /**
     * 获取用户角色统计 - 对应 count_users()
     *
     * @return 角色统计Map
     */
    Map<String, Object> getUserRoleStats();

    /**
     * 获取用户注册统计
     *
     * @param days 统计天数
     * @return 注册统计
     */
    Map<String, Object> getUserRegistrationStats(int days);

    // ========== WordPress 批量操作 ==========

    /**
     * 批量删除用户 - 对应 用户批量操作
     *
     * @param userIds 用户ID列表
     * @param reassignTo 重新分配内容的用户ID
     * @return 删除成功的数量
     */
    int batchDeleteUsers(List<Object> userIds, Object reassignTo);

    /**
     * 批量更新用户角色
     *
     * @param userIds 用户ID列表
     * @param role 新角色
     * @return 更新成功的数量
     */
    int batchUpdateUserRole(List<BigInteger> userIds, String role);

    /**
     * 批量更新用户状态
     *
     * @param userIds 用户ID列表
     * @param status 新状态
     * @return 更新成功的数量
     */
    int batchUpdateUserStatus(List<Object> userIds, Integer status);

    // ========== WordPress 用户元数据操作 ==========

    /**
     * 获取用户的所有元数据 - 对应 get_user_meta()
     *
     * @param userId 用户ID
     * @return 元数据列表
     */
    List<Usermeta> getUserMetas(Object userId);

    /**
     * 根据元数据键获取用户元数据 - 对应 get_user_meta()
     *
     * @param userId 用户ID
     * @param metaKey 元数据键
     * @return 元数据对象
     */
    Usermeta getUserMeta(Object userId, String metaKey);

    /**
     * 根据多个元数据键获取用户元数据
     *
     * @param userId 用户ID
     * @param metaKeys 元数据键数组
     * @return 元数据列表
     */
    List<Usermeta> getUserMetasByKeys(Object userId, String... metaKeys);

    /**
     * 获取用户元数据值 - 对应 get_user_meta()
     *
     * @param userId 用户ID
     * @param metaKey 元数据键
     * @return 元数据值
     */
    String getUserMetaValue(Object userId, String metaKey);

    /**
     * 获取用户元数据值（带默认值）
     *
     * @param userId 用户ID
     * @param metaKey 元数据键
     * @param defaultValue 默认值
     * @return 元数据值
     */
    String getUserMetaValue(Object userId, String metaKey, String defaultValue);

    /**
     * 保存用户元数据 - 对应 add_user_meta()
     *
     * @param usermeta 元数据对象
     * @return 保存是否成功
     */
    boolean saveUsermeta(Usermeta usermeta);

    /**
     * 更新用户元数据 - 对应 update_user_meta()
     *
     * @param usermeta 元数据对象
     * @return 更新是否成功
     */
    boolean updateUsermeta(Usermeta usermeta);

    /**
     * 删除用户元数据 - 对应 delete_user_meta()
     *
     * @param userId 用户ID
     * @param metaKey 元数据键
     * @return 删除是否成功
     */
    boolean deleteUserMeta(Object userId, String metaKey);

    /**
     * 删除用户的所有元数据
     *
     * @param userId 用户ID
     * @return 删除是否成功
     */
    boolean deleteAllUserMetas(Object userId);

    /**
     * 更新或保存用户元数据 - 对应 update_user_meta()
     *
     * @param usermeta 元数据对象
     * @return 操作是否成功
     */
    boolean saveOrUpdateUsermeta(Usermeta usermeta);

    /**
     * 批量更新用户元数据
     *
     * @param userId 用户ID
     * @param metaData 元数据键值对
     * @return 更新成功的数量
     */
    int batchUpdateUserMetas(BigInteger userId, Map<String, String> metaData);

    /**
     * 批量删除用户元数据
     *
     * @param userId 用户ID
     * @param metaKeys 元数据键列表
     * @return 删除成功的数量
     */
    int batchDeleteUserMetas(Object userId, List<String> metaKeys);

    // ========== WordPress 用户角色和能力 ==========

    /**
     * 获取用户能力列表 - 对应 user_can()
     *
     * @param userId 用户ID
     * @return 能力列表
     */
    List<String> getUserCapabilities(Object userId);

    /**
     * 检查用户是否具有指定能力 - 对应 user_can()
     *
     * @param userId 用户ID
     * @param capability 能力名称
     * @return 是否具有该能力
     */
    boolean hasCapability(Object userId, String capability);

    /**
     * 获取用户角色 - 对应 get_user_role()
     *
     * @param userId 用户ID
     * @return 角色名称
     */
    String getUserRole(Object userId);

    /**
     * 设置用户角色 - 对应 用户角色设置
     *
     * @param userId 用户ID
     * @param role 角色名称
     * @return 设置是否成功
     */
    boolean setUserRole(BigInteger userId, String role);

    /**
     * 添加用户能力
     *
     * @param userId 用户ID
     * @param capability 能力名称
     * @return 添加是否成功
     */
    boolean addUserCapability(BigInteger userId, String capability);

    /**
     * 移除用户能力
     *
     * @param userId 用户ID
     * @param capability 能力名称
     * @return 移除是否成功
     */
    boolean removeUserCapability(BigInteger userId, String capability);

    /**
     * 检查用户是否具有任意一个能力
     *
     * @param userId 用户ID
     * @param capabilities 能力名称数组
     * @return 是否具有任意一个能力
     */
    boolean hasAnyCapability(Object userId, String... capabilities);

    /**
     * 检查用户是否具有所有能力
     *
     * @param userId 用户ID
     * @param capabilities 能力名称数组
     * @return 是否具有所有能力
     */
    boolean hasAllCapabilities(Object userId, String... capabilities);

    // ========== WordPress 用户认证和密码 ==========

    /**
     * 验证用户密码 - 对应 wp_authenticate()
     *
     * @param userLogin 用户名
     * @param password 密码
     * @return 验证是否成功
     */
    boolean validatePassword(String userLogin, String password);

    /**
     * 更新用户密码 - 对应 wp_set_password()
     *
     * @param userId 用户ID
     * @param newPassword 新密码
     * @return 更新是否成功
     */
    boolean updatePassword(BigInteger userId, String newPassword);

    /**
     * 生成密码重置密钥 - 对应 get_password_reset_key()
     *
     * @param userId 用户ID
     * @return 重置密钥
     */
    String generatePasswordResetKey(BigInteger userId);

    /**
     * 验证密码重置密钥 - 对应 check_password_reset_key()
     *
     * @param userId 用户ID
     * @param resetKey 重置密钥
     * @return 验证是否成功
     */
    boolean validatePasswordResetKey(Object userId, String resetKey);

    /**
     * 清除用户会话 - 对应 会话清理
     *
     * @param userId 用户ID
     * @return 清除是否成功
     */
    boolean clearUserSessions(Object userId);

    /**
     * 获取用户登录记录
     *
     * @param userId 用户ID
     * @return 登录记录列表
     */
    List<Map<String, Object>> getUserLoginHistory(Object userId);

    // ========== WordPress 高级查询 ==========

    /**
     * 分页查询用户列表 - 对应 get_users() 分页
     *
     * @param pageNumber 页码
     * @param pageSize 每页数量
     * @param orderBy 排序字段
     * @param order 排序方向
     * @return 用户列表
     */
    List<Users> getUsersPaged(int pageNumber, int pageSize, String orderBy, String order);

    /**
     * 根据条件搜索用户 - 对应 用户搜索
     *
     * @param searchTerm 搜索词
     * @return 用户列表
     */
    List<Users> searchUsers(String searchTerm);

    /**
     * 高级搜索用户
     *
     * @param conditions 搜索条件
     * @return 用户列表
     */
    List<Users> searchUsersAdvanced(Map<String, Object> conditions);

    /**
     * 根据元数据值查找用户
     *
     * @param metaKey 元数据键
     * @param metaValue 元数据值
     * @return 用户列表
     */
    List<Users> findUsersByMetaValue(String metaKey, String metaValue);

    /**
     * 根据注册日期范围查找用户
     *
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 用户列表
     */
    List<Users> findUsersByRegistrationDate(Date startDate, Date endDate);

    /**
     * 根据最后登录时间查找用户
     *
     * @param days 天数
     * @return 用户列表
     */
    List<Users> findUsersByLastLogin(int days);

    /**
     * 根据角色查找用户
     *
     * @param role 角色名称
     * @return 用户列表
     */
    List<Users> findUsersByRole(String role);

    // ========== WordPress 用户内容关联 ==========

    /**
     * 获取用户发布的文章数量（应该归到PostService） - 对应 count_user_posts()
     *
     * @param userId 用户ID
     * @return 文章数量
     */
    long getUserPostCount(Object userId);

    /**
     * 获取用户发布的文章数量（按状态）（应该归到PostService）
     *
     * @param userId 用户ID
     * @param postStatus 文章状态
     * @return 文章数量
     */
    long getUserPostCountByStatus(Object userId, String postStatus);

    /**
     * 获取用户评论数量（应该归到CommentService）
     *
     * @param userId 用户ID
     * @return 评论数量
     */
    long getUserCommentCount(Object userId);

    /**
     * 重新分配用户内容 - 对应 用户删除时重新分配（应该归到PostService）
     *
     * @param fromUserId 原用户ID
     * @param toUserId 目标用户ID
     * @return 重新分配是否成功
     */
    boolean reassignUserContent(Object fromUserId, Object toUserId);

    /**
     * 获取用户媒体文件数量（应该归到PostService）
     *
     * @param userId 用户ID
     * @return 媒体文件数量
     */
    long getUserMediaCount(Object userId);

    // ========== WordPress 用户资料管理 ==========

    /**
     * 更新用户显示名称
     *
     * @param userId 用户ID
     * @param displayName 显示名称
     * @return 更新是否成功
     */
    boolean updateDisplayName(Object userId, String displayName);

    /**
     * 更新用户昵称
     *
     * @param userId 用户ID
     * @param nickname 昵称
     * @return 更新是否成功
     */
    boolean updateNickname(BigInteger userId, String nickname);

    /**
     * 更新用户网站URL
     *
     * @param userId 用户ID
     * @param website 网站URL
     * @return 更新是否成功
     */
    boolean updateWebsite(Object userId, String website);

    /**
     * 更新用户描述（个人简介）
     *
     * @param userId 用户ID
     * @param description 描述
     * @return 更新是否成功
     */
    boolean updateDescription(BigInteger userId, String description);

    /**
     * 更新用户头像
     *
     * @param userId 用户ID
     * @param avatarUrl 头像URL
     * @return 更新是否成功
     */
    boolean updateAvatar(BigInteger userId, String avatarUrl);

    // ========== WordPress 系统维护 ==========

    /**
     * 清理过期用户（未激活用户）
     *
     * @param days 过期天数
     * @return 清理的用户数量
     */
    int cleanupExpiredUsers(int days);

    /**
     * 重新生成用户激活密钥
     *
     * @param userId 用户ID
     * @return 新的激活密钥
     */
    String regenerateActivationKey(Object userId);

    /**
     * 同步用户元数据
     *
     * @param userId 用户ID
     * @return 同步是否成功
     */
    boolean syncUserMetadata(BigInteger userId);

    /**
     * 验证用户数据完整性
     *
     * @param userId 用户ID
     * @return 验证结果
     */
    boolean validateUserData(Object userId);

    /**
     * 修复用户数据
     *
     * @param userId 用户ID
     * @return 修复是否成功
     */
    boolean repairUserData(Object userId);

    // ========== WordPress 特定功能 ==========

    /**
     * 获取用户头像URL - 对应 get_avatar_url()
     *
     * @param userId 用户ID
     * @param size 头像尺寸
     * @return 头像URL
     */
    String getUserAvatarUrl(Object userId, Integer size);

    /**
     * 获取用户本地化信息 - 对应 locale
     *
     * @param userId 用户ID
     * @return 本地化代码
     */
    String getUserLocale(Object userId);

    /**
     * 设置用户本地化信息
     *
     * @param userId 用户ID
     * @param locale 本地化代码
     * @return 设置是否成功
     */
    boolean setUserLocale(BigInteger userId, String locale);

    /**
     * 获取用户管理员颜色方案
     *
     * @param userId 用户ID
     * @return 颜色方案
     */
    String getAdminColorScheme(Object userId);

    /**
     * 设置用户管理员颜色方案
     *
     * @param userId 用户ID
     * @param colorScheme 颜色方案
     * @return 设置是否成功
     */
    boolean setAdminColorScheme(BigInteger userId, String colorScheme);

    /**
     * 获取用户时区设置
     *
     * @param userId 用户ID
     * @return 时区
     */
    String getUserTimezone(Object userId);

    /**
     * 设置用户时区
     *
     * @param userId 用户ID
     * @param timezone 时区
     * @return 设置是否成功
     */
    boolean setUserTimezone(BigInteger userId, String timezone);

    /**
     * 获取用户日期格式
     *
     * @param userId 用户ID
     * @return 日期格式
     */
    String getUserDateFormat(Object userId);

    /**
     * 设置用户日期格式
     *
     * @param userId 用户ID
     * @param dateFormat 日期格式
     * @return 设置是否成功
     */
    boolean setUserDateFormat(BigInteger userId, String dateFormat);

    /**
     * 获取用户时间格式
     *
     * @param userId 用户ID
     * @return 时间格式
     */
    String getUserTimeFormat(Object userId);

    /**
     * 设置用户时间格式
     *
     * @param userId 用户ID
     * @param timeFormat 时间格式
     * @return 设置是否成功
     */
    boolean setUserTimeFormat(BigInteger userId, String timeFormat);

    /**
     * 获取用户起始星期
     *
     * @param userId 用户ID
     * @return 起始星期（0-6，0=星期日）
     */
    Integer getUserStartOfWeek(Object userId);

    /**
     * 设置用户起始星期
     *
     * @param userId 用户ID
     * @param startOfWeek 起始星期
     * @return 设置是否成功
     */
    boolean setUserStartOfWeek(BigInteger userId, Integer startOfWeek);

    // ========== 用户权限验证 ==========

    /**
     * 验证用户操作权限
     *
     * @param userId 用户ID
     * @param operation 操作名称
     * @return 是否有权限
     */
    boolean checkUserPermission(Object userId, String operation);

    /**
     * 获取用户权限列表
     *
     * @param userId 用户ID
     * @return 权限列表
     */
    List<String> getUserPermissions(Object userId);

    /**
     * 验证用户数据访问权限
     *
     * @param userId 用户ID
     * @param dataType 数据类型
     * @param dataId 数据ID
     * @return 是否有访问权限
     */
    boolean checkDataAccessPermission(Object userId, String dataType, Long dataId);

    // ========== 用户会话管理 ==========

    /**
     * 获取用户活跃会话
     *
     * @param userId 用户ID
     * @return 会话列表
     */
    List<Map<String, Object>> getUserActiveSessions(Object userId);

    /**
     * 终止用户会话
     *
     * @param userId 用户ID
     * @param sessionId 会话ID
     * @return 终止是否成功
     */
    boolean terminateUserSession(Object userId, String sessionId);

    /**
     * 终止用户所有会话
     *
     * @param userId 用户ID
     * @return 终止是否成功
     */
    boolean terminateAllUserSessions(Object userId);

    // ========== 用户导入导出 ==========

    /**
     * 导出用户数据
     *
     * @param userId 用户ID
     * @return 用户数据Map
     */
    Map<String, Object> exportUserData(Object userId);

    /**
     * 导入用户数据
     *
     * @param userData 用户数据
     * @return 导入的用户ID
     */
    Object importUserData(Map<String, Object> userData);

    /**
     * 批量导出用户数据
     *
     * @param userIds 用户ID列表
     * @return 用户数据列表
     */
    List<Map<String, Object>> batchExportUserData(List<Object> userIds);
}